Using Forms with Gen2

Using Forms to Collect Name Information

If you want to use different names each time you run the sample automation, manually adjusting the FirstName-Update and LastName-Update replace tasks would rebuild the automation each time, but it would also be highly inefficient. As a solution, it's far better to leave the automation "as is" and simply provide the name values when you run the automation. To accomplish this, you will need to use a JSON Form.

Likewise, running the automation from Automation Studio every time would not only be tedious but also require manual alterations that could unwittingly open the door to automation errors. To avoid this scenario, you will need to kick off the automation via JSON Form using Automation Catalog.

The docs.itential.com site contains more detailed user guides specific to Automation Catalog and JSON Forms

Access Automation Catalog

From the IAP home page:

1. Click the Automation Catalog menu option from the left navigation menu. The main page displays.

2. Click + CREATE AN AUTOMATION.

   Note: The "automation" terminology used here is somewhat of a misnomer. You won't actually be creating an automation as you did in Automation Studio. Instead you'll be providing access to an automation that's already built.

3. Give your automation the name "GenerateFacts".

4. Provide a description (optional).

5. Click the CREATE button.

In the GenerateFacts Automation Catalog window:

1. Select the "EnlightenMe" automation from the Automation list.

2. Click SAVE (lower-left corner).

3. Under the Form list, click the +NEW FORM button.

4. A Create modal displays asking you to specify what you would like to create.

   Figure 1. Create JSON Form

   

5. Select JSON Form.

6. Provide the name "GenFacts".

7. Provide a description (optional).

8. Click the Create button. This will open the JSON Form Builder .

Designing the JSON Form

To design your JSON Form:

1. Go the list of Form Elements on the right side.
2. Drag and drop the TEXT INPUT element onto the canvas.
3. Hover over the 3-dots menu icon and then click the cog icon to open the Configure dialog for TEXT INPUT.
4. Label the text element "FirstName".
5. Select "Yes" under the Required setting to make the "FirstName" label a required field.
6. Click SAVE.
7. Add another TEXT INPUT element and label it "LastName".
8. Make the "LastName" label a required field.
9. Click SAVE.

Figure 2. JSON Form

For more information on building forms, refer to the JSON Forms user guide on the docs.itential.com site.

Applying the JSON Form

Once you build the JSON Form, navigate back to the Automation Catalog entry "GenerateFacts" that was started earlier.

1. In the Form list box, select the GenFacts form you created.
2. Click SAVE.

Now let's take a moment and do a checkpoint.

So far, you have created an Automation Catalog entry that will display a newly built "GenFacts" form. Next, you will need to send the form values to the "EnlightenMe" automation, but keep in mind, the automation isn't expecting to receive input from a form. In this part of the process, you will need to update the automation to use the entry values from the JSON Form instead of the "Replace" tasks -- FirstName-Update and LastName-Update.

Update the Automation to Accept Form Inputs

To update the automation:

1. Click the App Grid icon in the header toolbar.

   Figure 3. App Grid

   

2. Select "Automation Studio" from the list.

3. Click the "Find an Automation" option (center of screen).

4. Find the "EnlightenMe" automation tile.

5. Click the stacked dots menu icon (lower-right corner of the tile).

6. Select Edit.

   Figure 4. Edit Automation

   

You are now back to the familiar Automation Builder canvas.

Setup the Form Query Tasks

The intent here is to consume the information from the GenFacts form instead of the hard-coded values contained in the "New Job Variable" tasks.

1. Add two new Query Tasks to the beginning of the automation.

2. Double-click the first Query task to edit the properties.

3. Change the Summary to "Form-FirstName".

4. Change the Description to a short comment that will make sense in the canvas tooltip. For example: "Isolate FirstName from form".

   The tool tip description should be clear and give the user a hint as to the purpose of that specific task.

5. Set the pass_on_null Reference Task variable to "False" (refer to the previously created "IsolateFact" query task as a reminder of how you did this earlier).

6. Set the query Reference Task variable to "firstName", which is the name of the field in the JSON Form you created.

   For compliance purposes, the "FirstName" field label on the GenFacts form is automatically converted to camelCase, making it firstName instead.

Change the Object Variable

You will need to change the obj variable manually:

1. Change the Reference Task to Job.
2. For the Reference Variable, select custom.
3. Manually enter the value formData (without quotes and case-senstive).
4. Click SAVE.

The first Query task is now configured to understand that it will be obtaining content from a JSON form. Now let's move on to the second Query task.

1. Configure the second Query task to be "Form-LastName".

   This query variable will search for lastName. Remember, the "LastName" field label is converted to camelCase on the GenFacts form.

2. Set the pass_on_null variable to "False".

3. For the obj variable, change the Reference Task to job.

4. For the Reference Variable, select custom.

5. Manually enter the value formData (without quotes and case-senstive).

   Figure 5. Set Variables

   

6. Click SAVE.

You should now have a series of nine (9) workflow tasks on the canvas.

1. START
2. Form-FirstName (query)
3. Form-LastName (query)
4. OriginalURL
5. FirstName-Update
6. LastName-Update
7. FetchFact
8. IsolateFact (query)
9. END

Figure 6. Complete Workflow

Update the Replace Tasks

Next, you will need to update the replace tasks to consume and work with the form values collected in the Query tasks you added.

1. Update the Firstname-Update task properties:
   • Set the newSubstr Reference task variable to the "Form-FirstName" task.
   • The Reference variable should automatically change to return_data.
2. Click Save.
3. Update the Lastname-Update task properties:
   • Set the newSubstr variable Reference task to the "Form-LastName" task.
   • The Reference variable should automatically change to return_data.
4. Click Save.

Note: After updating all the tasks, you could try to manually run the automation, but it will likely result in an error. This is because the automation is now expecting input from a JSON form; however, up until now you have not directly indicated "what form" the automation should expect input values from. You'll recall that the form name was specified within the "GenerateFacts" entry in Automation Catalog.

Test Run the Automation Catalog Entry

1. At this point, you should have saved the entire automation.

2. Click the App Grid icon in the header toolbar.

3. Select "Automation Catalog" from the list of options.

4. Click Find Automation.

5. Find the "GenerateFacts" automation tile.

6. Click the Play icon (lower-right corner).

7. The GenFacts form displays in a modal window.

8. Provide FirstName and LastName values.

9. Click START (lower-left corner). The modal window is replaced with a Run Automation notification window.

   Figure 7. Notification Message

   

10. Click the VIEW JOB button to open the Job Manager page.

11. Find the IsolateFact task in the job list.

12. Click the book icon to view the OUTGOING value.

You should observe that "Chuck Norris" has been replaced by whatever name input you gave in the "GenerateFacts" Automation (form) initiated from Automation Catalog.

Summary Wrap-Up

Kudos, what great work you've done! You completed all the sections of this quick start tour from start to finish. Let's review all that you've accomplished on your journey:

• Created an automation that utilizes tasks to obtain data from a remote system.
• Viewed active jobs in Job Manager and navigate to the Outgoing tab to view task results.
• Used additional task inputs that interacted with values presented by other tasks in the automation.
• Customized an automation to accept user input.
• Created an Automation Catalog entry that uses a custom JSON Form to obtain input that's passed to an automation.

After completing this guide, you should be well on your way to using all the the basic capabilities of your IAP instance. To expand your knowledge further, refer to the Itential Automation Platform User Guides provided on the docs.itential.com site for more detailed information.